------------------------------------------------------------------------------

// ANIMATION LIB VERSION 2!//
// BY: Grimfate126 //
// RELEASE DATE: 9-2-06 //

------------------------------------------------------------------------------

this version adds the ability to load and play animations from a sprite sheet! 
currently only vertical and horizontal modes are included. (more will be explained later)

added BMP as a valid extension, thx to youresams bmplib!
------------------------------------------------------------------------------

.://FUNCTIONS \\:.

AnimLoad(header, frames, anim_Id, extension)

AnimEdit(timer_name, command)

AnimBlit(Id, anim_x, anim_y, timer_name, counter, delay)

-- NEW FUNCTIONS --

AnimLoadSs(ss_id, extension, filename) // loads images from a sprite sheet.

AnimBlitSs(ss_d, ss_x, ss_y, ss_timer, ss_counterx, ss_countery, ss_delay, ss_width, ss_height, ss_number, ss_mode) 
// blits animations from sprite sheet.

------------------------------------------------------------------------------

------------------------------------------------------------------------------

.:// AnimLoad(header, frames, anim_Id, extension) \\:.


NOTE: ALL animation frames MUST be in the format of: header, then frame number, then extension.

This function load an animation depending on the arguments that you give it.

"header" stands for the beginning name of the image.

EXAMPLE:

Suppose we have 4 images:

test1.png
test2.png
test3.png
test4.png

here, our header would be "test", our frame number would be either 1, 2, 3, or 4, AND our extension would be "png" 
(we dont need the period cause the function automatically does that.)

NOW, there is only one thing left, anim_Id.

anim_Id is an array that YOU WILL HAVE TO MAKE IN YOUR OWN CODE. 

if thats confusing, (which is probably is) here is how we would load an animation which had the images test1.png, test2.png
etc:


-- START CODE --

example = {}
AnimLoad("test", 4, example, "png")

-- note that the words test and png are in quotes.

-- END CODE --

the above code will load the images test1.png, test2.png, test3.png, AND test4.png into an array called "example".

check the example that i wrote, which should have come with this, if you are sill confused. 

------------------------------------------------------------------------------

------------------------------------------------------------------------------

.://AnimBlit(Id, anim_x, anim_y, timer_name, counter, delay)\\:.

this function takes 6 arguments:

1. Id - this is the array you created. (like 'example' in the above section)
2. anim_x = this is the x position of the animation
3. anim_y, this is the y position of the animation.
4. timer_name - this is the name of the timer THAT YOU MUST CREATE IN YOUR OWN CODE.
(ill explain below)
5. counter - this is a var that will count what frame you are on. you can put anything here.
the easiest thing to do is put the number 0.
6. delay - this is the delay between each frame (in milliseconds)

SO, lets take the two sections and make a animation: 

-- CODE START -- 

example = {}
example_timer = Timer.new() -- this is the timer you have to create. it can also be named anything.

AnimLoad("test", 4, example, "png")

while true do

	AnimBlit(example, 50, 50, example_timer, example_counter, 200)

screen.waitVblankStart()
screen:flip()
end

-- CODE END --

that code will display an animation at 50, 50 on the psp screen.

------------------------------------------------------------------------------

------------------------------------------------------------------------------

.://AnimEdit(timer_name, command)\\:.

this is used to edit the timer. this function takes only 2 arguments:

1. timer_name - this is the name of the timer you want to edit. (in the above case it would be example_timer)
2. command - this is what you want it to do:

puttting: AnimEdit(example_timer, 1) will start the timer.
puttting: AnimEdit(example_timer, 2) will stop/pause the timer.
puttting: AnimEdit(example_timer, 3) will reset the timer to 0.

------------------------------------------------------------------------------

------------------------------------------------------------------------------
.://AnimLoadSs(ss_id, extension, filename)\\:.

NOTE: ('ss' stands for sprite sheet)

this function will load a sprite sheet into an array. the function takes three arguments:

1. ss_id - this is an array THAT YOU MUST CREATE . the sprite sheet will be loaded into this array.
2. extension - this is the extension of the sprite sheet. supported formats are png, jpg, and bmp.
3. filename - this is the name of the file. (DO NOT put the extension or the period in this argument. 
the functions does that for you.)

this is how we would load a sprite sheet that was called: "testH.png"

--START CODE--

sstestV = {}
sstest_timerV = Timer.new() -- you also need to make a timer for your sprite sheets.

AnimLoadSs(sstestV, "png", "testV")

--END CODE--


IMPORTANT: 

as of now, you can ONLY load sprite sheets that are either going vertically or horizontally. confused? 
look at the images called "testV.png" and "testH.png".

testV is what i mean by going "vertically". there is only ONE image per row. and there are 4 rows
testH is what i mean by going "horizontally". there is only ONE image per column. and there are 4 columns.

NOW, look at "test_NOT_VALID_RIGHT_NOW.png".

that sprite sheet has 3 frames per row and 3 frames per column. THAT IS NOT VALID AS OF NOW.
im woking on it after this.

------------------------------------------------------------------------------

------------------------------------------------------------------------------

.://AnimBlitSs(ss_d, ss_x, ss_y, ss_timer, ss_counterx, ss_countery, ss_delay, ss_width, ss_height, ss_number, ss_mode)\\:. 

ok, here we go. this function will blit animation frames from a sprite sheet. this function takes 11 
arguments. DONT WORRY. its very easy once you get it.

1. ss_d - this is the array in which your sprite sheet is located.
2. ss_x - this is the X position of where you want to blit the frame.
3. ss_y - this is the Y position of where you want to blit the frame.
4. ss_timer - this is a timer that you MUST CREATE IN YOUR OWN CODE. 
it will time the delay between frames.
5. ss_counterx - this will count what X frame is being blit. keep this to zero. 
6. ss_countery - this will count what Y frame is being blit. keep this to zero.
7. ss_delay - this is the delay that you want in-between frames. (in milliseconds)
8. ss_width - this is the width of the all the frames. NOT THE WIDTH OF THE SPRITE SHEET!!
9. ss_height - this is the height of the all the frames. NOT THE HEIGHT OF THE SPRITE SHEET!!
10. ss_number - this is the number of frames in your sprite sheet.
11. ss_mode - this will be set to either "horizontal" or "vertical" (WITH the quotes)

if your sprite sheet is going horizontally (read above passage) then put "horizontal".
if your sprite sheet is going vertically (read above passage) then put "vertical".

------------------------------------------------------------------------------

------------------------------------------------------------------------------

to use:

simply put : dofile("animLib.lua") OUTSIDE of your main loop.

thats it! youre now ready to use animLib!

------------------------------------------------------------------------------

------------------------------------------------------------------------------

if you use this, please give credit to Grimfate126. if you forget, thats ok. (try not to "forget" on purpose ;)

if you use bmplib please give credit to youresam. 

HaVe FuN!!!!!

